---
description: Learn how to specify the documents field in your GraphQL Code Generator config file.
---

import { Callout } from '@theguild/components'

# `documents` field

The `documents` field should point to your GraphQL documents: `query`, `mutation`, `subscription`, and `fragment`.

`documents` is only required if you use plugins that generate code for the client-side.

You can specify either a `string` pointing to your documents or `string[]` pointing to multiple documents.

## How to use it?

### Root-level

You can specify the `documents` field in your root level config:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'http://localhost:3000/graphql',
  documents: 'src/**/*.graphql',
  generates: { './src/types.ts': { plugins: ['typescript', 'typescript-operations'] } }
}
export default config
```

### Output-file level

You can also specify the `documents` field in your generated file level config:

```ts {7}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'http://server1.com/graphql',
  generates: {
    './src/types1.ts': {
      documents: 'src/**/*.graphql',
      plugins: ['typescript', 'typescript-operations']
    }
  }
}
export default config
```

### Document Scanner

GraphQL Code Generator has a built-in document scanner, which means you can specify a `.graphql` file or code files containing GraphQL documents (ex: `.tsx`).

You can tell it to find documents in TypeScript files:

```ts /!(*.d).{ts,tsx}/
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'http://server1.com/graphql',
  documents: 'src/**/!(*.d).{ts,tsx}'
}
export default config
```

## Available Formats

The following can be specified as a single value or as an array with mixed values.

- ### Local File

You can specify a `string` to point to a single file:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: 'my-query.graphql'
  // ...
}
export default config
```

Or `string[]` to point to multiple files:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['my-query.graphql', 'my-other-query.graphql']
  // ...
}
export default config
```

- ### Glob Expression

You can specify a Glob expression in order to load multiple files:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: './src/**/*.graphql'
  // ...
}
export default config
```

You can also specify multiple Glob expressions as an array:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/dir1/*.graphql', './src/dir2/*.graphql']
  // ...
}
export default config
```

You can specify files to exclude by prefixing the Glob expression with `!`:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/**/*.graphql', '!*.generated.graphql']
  // ...
}
export default config
```

<Callout>All provided glob expressions are evaluated together. The usage is similar to `.gitignore`.</Callout>

Additionally, you can use code files, and the codegen will try to extract the GraphQL documents from it:

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx']
  // ...
}
export default config
```

The codegen will try to load the file as an AST and look for exact GraphQL operations strings. Still, if it can't find those, it will try to `require` the file and look for operations in the default export.

You can disable the `require` if it causes errors for you (for example, because of different module system):

```ts {7}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: {
    './src/*.jsx': {
      noRequire: true
    }
  }
  // ...
}
export default config
```

<Callout>
Your operations should be declared as template strings with the `gql` tag or with a GraphQL comment (`` const myQuery = /* GraphQL */ `query { … }` ``). This can be configured with `pluckConfig` (see below).
</Callout>

- ### String

You can specify your GraphQL documents directly as an AST string in your config file. It's very useful for testing.

```ts {5}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['query { f1 }', 'query { f2 }']
  // ...
}
export default config
```

## GraphQL Tag Pluck

GraphQL Code Generator uses `graphql-tag-pluck` internally to extract GraphQL documents from your code file.

If you are pointing to a code file (such as `.js` or `.jsx`), GraphQL will try to look for usages of `gql` tag, or string literals that are using magic GraphQL comment (`/* GraphQL */`), for example:

```jsx {5-11,14-20}
import React from 'react'
import { gql } from 'graphql-tag'

// This will work
const MY_QUERY = gql`
  query myQuery {
    getSomething {
      id
    }
  }
`

// This will also work
const MY_QUERY = /* GraphQL */ `
  query myQuery {
    getSomething {
      id
    }
  }
`

// … some components code …
```

By default, it has a predefined list of popular `gql` tags to look for, in order to make sure it's not trying to extract an invalid or unrelated string. [The default list could be found here](https://github.com/ardatan/graphql-tools/blob/master/packages/graphql-tag-pluck/src/visitor.ts#L12)

You can add custom tags if you need by using `pluckConfig` on the root level on your config file:

```ts {6-13}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    modules: [
      {
        name: 'my-custom-module'
        identifier: 'gql'
      }
    ]
  }
  // ...
}
export default config
```

You can also customize globally used identifiers, like that:

```ts {7}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    globalGqlIdentifierName: ['gql', 'graphql', 'myCustomGlobalGqlTag']
  }
  // ...
}
export default config
```

And you can customize the magic GraphQL comment by doing:

```ts {7}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: ['./src/*.jsx'],
  pluckConfig: {
    gqlMagicComment: 'customcomment'
  }
  // ...
}
export default config
```

## Custom Document Loader

Suppose your schema has a different or complicated way of loading. In that case, you can specify a custom loader with the `loader` field.

```ts {6-8}
import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  // ...
  documents: {
    './src/*.jsx': {
      loader: 'my-documents-loader.js'
    }
  }
  // ...
}
export default config
```

Your custom loader should export a default function that returns a `DocumentNode`. For example:

```js
const { readFileSync } = require('node:fs')
const { parse } = require('graphql')

module.exports = (docString, config) => {
  return parse(readFileSync(docString, 'utf8'))
}
```

<Callout>
  The second parameter passed to the loader function is a config object that includes a `pluginContext` property.
  `pluginContext` is passed to any executed plugins, so it can be modified by the loader to pass any additional
  information to those plugins.
</Callout>
